Convert

Convert an amount from one currency to another using the current rate for the requesting Merchant. The conversion uses the same rate as the Get FX Rate API, within the validity period of that quote.

The direction (and therefore which rate is applied) is derived from the order of from_currency and to_currency:

Converting a foreign currency → VND (the customer sells the foreign currency) applies the bid rate.
Converting VND → a foreign currency (the customer buys the foreign currency) applies the ask rate.

The applied side is returned in rate_type, and the response carries the same quote_code so the quote can be reconciled (and, in a later phase, locked).

Path

URL: /cb-core/api/v1/fx/convert
Method: POST
Description: Convert an amount between two currencies using the current rate.

Request

Request table

Params	Data Type	Required	Description
request_id	string(50)	Yes	Unique code that identifies the request. Suggested format: MerchantCode + BK + YYYYMMDD + UniqueId
request_time	string(19)	Yes	Time the Merchant sends the request. Format: YYYY-MM-DD HH:MM:SS
merchant_code	string(20)	Yes	Merchant code provided by Baokim before integration
from_currency	string(10)	Yes	The currency being converted from (e.g. `USD`). Only one currency code is allowed
to_currency	string(10)	Yes	The currency being converted to (e.g. `VND`). Only one currency code is allowed
amount	decimal(18,2)	Yes	The amount, expressed in `from_currency`, to be converted

Request Example

{
  "request_id": "MERCHANT1234BK202606053",
  "request_time": "2026-06-05 10:15:30",
  "merchant_code": "MERCHANT1234",
  "from_currency": "USD",
  "to_currency": "VND",
  "amount": 1000.00
}

Response

Response Table

Params	Data Type	Required	Description
response_code	int(4)	Yes	Result code from Baokim, as per the Error Codes table
response_message	string(200)	Yes	Description of the result code
merchant_code	string(20)	Yes	Merchant code provided by Baokim before integration
data	Object	Yes	Conversion result

Data Object Structure (inside `data`)

Params	Data Type	Description
currency_pair	string(10)	Currency pair used for the conversion, in `BASE/QUOTE` format (e.g. `USD/VND`)
from_currency	string(10)	The currency converted from
to_currency	string(10)	The currency converted to
amount	decimal(18,2)	The input amount, expressed in `from_currency`
converted_amount	decimal(18,2)	The resulting amount, expressed in `to_currency`
rate	decimal(18,4)	The applied rate (VND per 1 unit of the foreign currency)
rate_type	string(3)	The side applied: `bid` or `ask`
quote_code	string(50)	Quote code for this rate. Used for reconciliation and reserved for rate-lock
last_updated	string(19)	Time the rate was last refreshed. Format: YYYY-MM-DD HH:MM:SS
valid_until	string(19)	Time until which the quote is valid. May be `null` in the current phase

Response Example

{
  "response_code": 200,
  "response_message": "Success",
  "merchant_code": "MERCHANT1234",
  "data": {
    "currency_pair": "USD/VND",
    "from_currency": "USD",
    "to_currency": "VND",
    "amount": 1000.00,
    "converted_amount": 26450000.00,
    "rate": 26450.0000,
    "rate_type": "bid",
    "quote_code": "FXQ20260605101530USDVND0001",
    "last_updated": "2026-06-05 10:15:00",
    "valid_until": "2026-06-05 10:16:00"
  }
}

Error Code

Response Code	Response Message
200	Success
101	System Error
110	Merchant Code Invalid
120	Invalid Signature
404	Currency Pair Not Supported
422	Validation Error
423	FX Rate Not Available
429	Too Many Requests

Path​

Request​

Request table​

Request Example​

Response​

Response Table​

Data Object Structure (inside data)​

Response Example​

Error Code​